/*
 * Package il.ac.biu.cs.grossmm.cpp
 * File CppServiceFactory.java
 * 
 * This is a part of presence service framework API. 
 * See javadoc for more information.
 *  
 * Copyright (C) 2006 Grossmann Mark
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */
package il.ac.biu.cs.grossmm.api.cpp;

import il.ac.biu.cs.grossmm.api.keys.KeyPattern;

/**
 * Manages persistent and non-persistant CPP service providers.
 * <p>
 * Non-persistant service providers do not store subscriptions in a persistant
 * storage and therefore may provide a faster operation. Non-persistant service
 * providers are not shared: the CPP service consumers for these providers do
 * not see subscriptions of each other.
 * <p>
 * A persistant service provider stores subscription information in a persistant
 * storage and therefore may operate slower then non-persistent providers.
 * Persistent CPP service providers are identified by symbolic identifiers.
 * These identifiers are associated with them when invoking
 * <tt>getServiceProvider</tt> method with a identifeir which does not match
 * any existing CPP service provider identifier. Subsequent invokations of
 * <tt>getServiceProvider</tt> method with the same identifier returns a
 * reference to the same CPP servie provider (i.e. with the same set of
 * susbcription information). Persistent service providers must be removed when
 * no longer needed by invoking <tt>removeServiceProvider</tt> method.
 * Persistent CPP service providers are not shared, all notifications are sent
 * to the CPP service provider used in the last call which obtained a reference
 * to CPP service provider.
 * <p>
 * For both types of CPP service providers a t-class and a key pattern should be
 * specified in invokation of corresponding <tt>getServiceProvider</tt>
 * methods. The key pattern restricts the data keys that can be used in
 * subscription operations. The t-class specifies the java class for contents of
 * the notification to be used in notification operations.
 * 
 */
public interface CppServiceManager {
	/**
	 * Creates a new non-persistent CPP service provider
	 * 
	 * @param <T>
	 *            the java class for contents of the notification to be used in
	 *            notification operations
	 * @param tClass
	 *            specifies the java class for contents of the notification to
	 *            be used in notification operations.
	 * @param consumer
	 *            CPP consumer to receive notifications
	 * @param pattern
	 *            the key pattern to restrict the data keys that can be used in
	 *            subscription operations.
	 * @return a new non-persistent CPP service provider
	 */
	<T> CppServiceProvider<T> getServiceProvider(Class<T> tClass,
		CppServiceConsumer<T> consumer, KeyPattern pattern);

	/**
	 * Creates a new persistent CPP service provdier or returns an existing one,
	 * depending on whether the idientifier parameter matches any existing CPP
	 * service provider.
	 * <p>
	 * When identifier matches an existing CPP service provider, the of the
	 * parameters, for exception of the consumer, should match to those used in
	 * invokation of this method when the CPP service provider was created
	 * 
	 * 
	 * @param <T>
	 *            the java class for contents of the notification to be used in
	 *            notification operations
	 * @param tClass
	 *            specifies the java class for contents of the notification to
	 *            be used in notification operations.
	 * @param consumer
	 *            CPP consumer to receive notifications
	 * @param pattern
	 *            the key pattern to restrict the data keys that can be used in
	 *            subscription operations.
	 * @param identifier
	 *            unique identifier of a CPP service provider
	 * @return CPP service provider
	 */
	<T> CppServiceProvider<T> getServiceProvider(Class<T> tClass,
		CppServiceConsumer<T> consumer, KeyPattern pattern, String identifier);

	/**
	 * Removes existing persistent CPP service provider. After removal all
	 * subscription information associated with the specified service provider
	 * is discarded and no more notifications are ever sent.
	 * 
	 * @param <T> the java class for contents of the notification to be used in
	 *            notification operations
	 * @param identifier unique identifier of a CPP service provider
	 * 
	 */
	void removeServiceProvider(String identifier);

}
